home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / cmdline.lha / cmdline / doc / parsing.man < prev   
Text File  |  1993-04-13  |  5KB  |  98 lines
  1. .SH PARSING
  2. Although, much of the parsing behavior of \*(NM can be configured at run-time
  3. there are some \fIcommon rules\fP that are used when parsing command-line
  4. arguments.  Many of these so called \fIrules\fP are just a formalization
  5. of things that have become an informal standard over the years.
  6.  
  7. .SS "LONG AND SHORT OPTIONS"
  8. .RS
  9. By default, \*(NM will allow both single-character options \fIand\fP
  10. keywords (long-options) to be matched on the command-line.
  11. Under Unix, a single character option is prefixed by the string ``\-''.
  12. and a long-option is prefixed by the string ``\*(--''.
  13. (If desired, the string ``+'' may also be used as a long-option prefix
  14. by explicitly specifying the corresponding flag).  If a token
  15. on the command-line exactly matches the string ``\*(--'', then all
  16. further matching of options (both long and short) are disabled and
  17. any remaining arguments are considered to be positional parameters
  18. (even if they look like options).
  19.  
  20. If short-option processing is disabled, then the prefix ``\-'' may be used
  21. to indicate a long-option (the ``\*(--'' prefix will still be accepted).
  22. .RE
  23.  
  24. .SS "OPTION MATCHING"
  25. .RS
  26. By default, short-option matching is case-sensitive (but case-insensitive
  27. matching may be used if desired). Long-options are always matched 
  28. case-insensitive and only a unique prefix of the long-option name needs
  29. to be given in order for it to be matched successfully.
  30. .RE
  31.  
  32. .SS "SPECIFYING VALUES TO OPTIONS"
  33. .RS
  34. By default, \*(NM will allow the value for an option to be in the
  35. same command-line token as the option itself, or in a separate
  36. command-line token.  For short-options, specifying the value in
  37. the same token simply means immediately following the option
  38. character with the intended value as in "\fB\-c\fIvalue\fR".
  39. For long-options, specifying the value in the same token requires
  40. that the value be separated from the keyword name by an equal-sign
  41. (`=') or by a colon (`:') as in ``\fB\*(--keyword\fP=\fIvalue\fP''
  42. or ``\fB\*(--keyword\fP:\fIvalue\fP''.
  43.  
  44. When specifying values to short-options in the same token as the option
  45. itself, the "portion" of the value that is consumed depends upon
  46. the option type. For options that represent a character value, only
  47. the character immediately following the option-character is consumed
  48. and the remaining characters in the token may match other options.
  49. For options that represent a numeric value, only the portion of the
  50. token that "looks" like a number will be consumed and the remaining
  51. characters in the token may match other options. For options that
  52. represent a string value, all remaining characters in the token
  53. are consumed. What this means is that if I have an integer option
  54. \fB\-i\fP, a character option \fB\-c\fP and a string option \fB\-s\fP,
  55. then they may all be specified on the command-line using the single token
  56. ``\fB\-i\fI100\fBc\fIc\fBs\fIstring\fR''.
  57.  
  58. It should be noted that integer valued options may be specified on the
  59. command-line in decimal, hexadecimal, or octal notation.
  60. Hexadecimal notation is assumed if the first two characters of the
  61. integer are ``\f40x\fP'' or ``\f40X\fP'';
  62. octal notation is assumed if the first digit of the integer is `0';
  63. decimal notation is assumed for all other cases.
  64. .RE
  65.  
  66. .SS "VALUES FOR BOOLEAN OPTIONS"
  67. .RS
  68. \*(NM allows boolean options to take optional values. If a boolean option
  69. appears by itself without a value then the default action (which is
  70. usually to turn itself \fIon\fP) is used.  One may also explicitly specify
  71. the boolean value to use by supplying a value \fIin the same token as the
  72. option\fP.
  73.  
  74. For short options, a single character is used as the boolean value.
  75. Other short-option characters may immediately follow the boolean
  76. value (in the same token as the boolean option) because only one
  77. character is consumed for the boolean value. 
  78. The following strings may be used to indicate a value to a boolean option
  79. (those strings that contain more than 1 character may only be used in
  80. conjunction with long-options):
  81. .RS
  82. .TP
  83. "\f40\fP", "\f4\-\fP", "\f4OFF\fP", "\f4NO\fP", "\f4FALSE\fP"
  84. Each of these indicates that the option should be turned \fIoff\fP.
  85.  
  86. .TP
  87. "\f41\fP", "\f4+\fP", "\f4ON\fP", "\f4YES\fP", "\f4TRUE\fP"
  88. Each of these indicates that the option should be turned \fIon\fP.
  89.  
  90. .TP
  91. "\f4^\fP", "\f4~\fP", "\f4!\fP"
  92. Each of these indicates that the option should be \fItoggled\fP.
  93. In the case of a long-option, any of the above characters may also be followed
  94. by the keyword-name of the option (as in ``\fB\*(--mode\f4=!mode\fR'').
  95. .RE
  96.  
  97. .RE
  98.